Серіалізація TypeScript: шаблони безпеки типів JSON

У постійно мінливому ландшафті веб-розробки забезпечення цілісності даних і запобігання помилкам під час виконання мають першорядне значення. TypeScript, з його надійною системою типів, надає потужний механізм для досягнення цих цілей, особливо при роботі з серіалізацією та десеріалізацією JSON. Цей вичерпний посібник досліджує різні шаблони та методи для реалізації безпечної обробки JSON у ваших проектах TypeScript, дозволяючи вам створювати більш надійні та зручні в обслуговуванні додатки для глобальної аудиторії.

Розуміння проблеми: JSON та система типів TypeScript

JSON (JavaScript Object Notation) є фактичним стандартом обміну даними в Інтернеті. Однак, притаманна JSON нетипізована природа створює проблеми при інтеграції зі статично типізованою мовою, такою як TypeScript. Без належного забезпечення типів розробники ризикують зіткнутися з помилками під час виконання через розбіжності типів, несподівані формати даних або відсутні поля. Це може призвести до збоїв додатків, вразливостей безпеки та розчарованих користувачів у всьому світі.

Розглянемо сценарій, коли ви отримуєте дані з публічного API. Документація API стверджує, що певна кінцева точка повертає масив об’єктів користувачів, кожен з яких містить властивості `id`, `name` та `email`. Без безпеки типів ви можете припустити структуру даних і почати використовувати її у своєму додатку. Однак, що станеться, якщо API змінить формат відповіді, введе нові поля або змінить типи даних існуючих полів? Ваш додаток може зламатися, що призведе до погіршення взаємодії з користувачем.

TypeScript вирішує цю проблему, дозволяючи визначати інтерфейси або типи, які представляють структуру ваших даних JSON. Це дозволяє компілятору TypeScript перевіряти наявність помилок типу під час компіляції, запобігаючи багатьом потенційним проблемам під час виконання. Забезпечуючи безпеку типів під час серіалізації та десеріалізації, ви можете значно підвищити надійність і зручність підтримки своєї кодової бази.

Основні концепції та методи

1. Визначення інтерфейсів і типів TypeScript

Основою безпечної обробки JSON є визначення інтерфейсів або типів TypeScript, які точно моделюють вашу структуру даних JSON. Інтерфейс визначає контракт для форми об’єкта, вказуючи типи даних його властивостей. Псевдонім типу надає більш стислий спосіб створення власних типів.

Приклад:

            interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: { //Optional property
      street: string;
      city: string;
      country: string;
  }
}

//Alternatively using type
type UserType = {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: {
      street: string;
      city: string;
      country: string;
  }
}

            

              
                Copy
              
            
          

У цьому прикладі інтерфейс `User` визначає очікувану структуру об’єкта користувача. Властивість `address` є необов’язковою, що позначається символом `?`, який є поширеним шаблоном для обробки потенційно відсутніх даних. Використання інтерфейсів і псевдонімів типів забезпечує перевірку типів під час компіляції, зменшуючи ризик помилок під час виконання при роботі з даними JSON.

2. Серіалізація: перетворення об’єктів TypeScript у JSON

Серіалізація — це процес перетворення об’єкта TypeScript у рядок JSON. Зазвичай це робиться під час надсилання даних на сервер або збереження їх у базі даних. Система типів TypeScript надає гарантії під час компіляції, що об’єкт відповідає визначеному типу, запобігаючи несподіваним помилкам. Вбудований метод `JSON.stringify()` використовується для серіалізації. Однак важливо враховувати крайні випадки, такі як власні типи об’єктів або об’єкти дат під час серіалізації.

Приклад:

            const user: User = {
  id: 123,
  name: 'John Doe',
  email: 'john.doe@example.com',
  isActive: true,
  address: {
      street: '123 Main St',
      city: 'Anytown',
      country: 'USA'
  }
};

const userJSON: string = JSON.stringify(user, null, 2); // Pretty-printed JSON with 2 spaces for indentation
console.log(userJSON);

            

              
                Copy
              
            
          

Цей фрагмент коду демонструє, як серіалізувати об’єкт `User` у рядок JSON за допомогою `JSON.stringify()`. Другий аргумент, `null`, — це функція заміни, яка дозволяє налаштувати процес серіалізації. Третій аргумент, `2`, визначає кількість пробілів, які використовуватимуться для відступів, що робить вихід JSON більш читабельним. У реальному додатку розгляньте обробку помилок, які можуть виникнути під час `JSON.stringify()`, і налаштуйте його для обробки об’єктів Date та інших спеціальних типів.

3. Десеріалізація: перетворення рядків JSON в об’єкти TypeScript

Десеріалізація — це процес перетворення рядка JSON назад в об’єкт TypeScript. Зазвичай це робиться під час отримання даних з сервера або читання їх з файлу. Тут важлива безпека типів. Безпосереднє приведення результату `JSON.parse()` до визначеного інтерфейсу не виконуватиме автоматичну перевірку типу. Він лише повідомляє компілятору, що потрібно «довіряти», що дані мають вказаний тип. Будь-яка розбіжність між даними та інтерфейсом призведе до помилок під час виконання.

Для безпечної десеріалізації JSON існує кілька підходів, кожен зі своїми перевагами та недоліками. Це передбачає ретельну перевірку даних, щоб переконатися, що вхідні дані JSON відповідають очікуваній структурі та типам даних.

3.1 Пряме приведення (з обережністю)

Цей підхід передбачає використання твердження типу для приведення результату `JSON.parse()` до вашого інтерфейсу. Це найпростіший, але й найризикованіший спосіб десеріалізації даних JSON, оскільки він не виконує перевірку під час виконання. Він просто повідомляє компілятору, що дані відповідають типу. Цей метод працює, коли ви *довіряєте* джерелу JSON, наприклад, з вашого внутрішнього API або коду, який ви контролюєте.

Приклад:

            const userJSON: string = '{
  "id": 123,
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "isActive": true
}';

const user: User = JSON.parse(userJSON) as User;
console.log(user.name);

            

              
                Copy
              
            
          

У цьому прикладі результат `JSON.parse(userJSON)` приводиться до інтерфейсу `User`. Хоча це компілюється без помилок, якщо рядок `userJSON` не відповідає інтерфейсу `User` (наприклад, відсутня властивість або неправильний тип даних), ви зіткнетеся з помилками під час виконання під час доступу до властивостей.

3.2 Перевірка за допомогою бібліотек (рекомендовано)

Використання спеціальної бібліотеки валідації є рекомендованим підходом для безпечної десеріалізації. Такі бібліотеки, як `zod`, `io-ts` і `class-validator`, надають надійні функції для перевірки даних JSON відповідно до визначеної схеми. Ці бібліотеки дозволяють описати очікувану структуру та типи даних і автоматично перевіряти дані під час виконання, надаючи докладні повідомлення про помилки в разі збою перевірки.

Використання Zod: Zod — популярна бібліотека для валідації схем із простим та інтуїтивно зрозумілим API. Легко визначити схеми та перевірити дані на їх відповідність. Спочатку встановіть Zod:

            npm install zod
            

              
                Copy
              
            
          

Потім використовуйте Zod, щоб визначити схему, що відповідає вашому інтерфейсу. Припустимо, що у нас є інтерфейс `User`, визначений вище.

            import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(), // Email validation
  isActive: z.boolean(),
  address: z.optional(z.object({
    street: z.string(),
    city: z.string(),
    country: z.string()
  }))
});

interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: {
    street: string;
    city: string;
    country: string;
  }
}

            

              
                Copy
              
            
          

Тепер ми можемо проаналізувати та перевірити рядок JSON:

            const userJSON: string = '{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "isActive": true
}';

try {
    const parsedUser: User = UserSchema.parse(JSON.parse(userJSON));
    console.log(parsedUser.name);
} catch (error: any) {
    console.error('Validation error:', error.errors);
}

            

              
                Copy
              
            
          

У цьому прикладі `UserSchema.parse(JSON.parse(userJSON))` намагається проаналізувати та перевірити рядок `userJSON`. Якщо дані не відповідають схемі, виникає `ZodError`, що дозволяє вам обробляти помилки валідації ввічливо. Блок `try...catch` обробляє будь-які помилки валідації, які можуть виникнути. Це безпечніший і надійніший метод десеріалізації даних JSON.

Використання io-ts: io-ts — це бібліотека, яка поєднує перевірку типів під час виконання з концепціями функціонального програмування. Це дозволяє визначати кодеки, які кодують і декодують дані та перевіряють дані JSON відповідно до цих кодеків. Почати роботу з ним складніше, але він надає більш потужні функції для складних сценаріїв валідації.

            npm install io-ts

            

              
                Copy
              
            
          

            import * as t from 'io-ts';
import { isRight } from 'fp-ts/lib/Either';

const UserCodec = t.type({
  id: t.number,
  name: t.string,
  email: t.string,
  isActive: t.boolean,
  address: t.union([ //using union to represent either address or undefined
    t.undefined,
    t.type({
        street: t.string,
        city: t.string,
        country: t.string
    })
  ])
});

interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: {
    street: string;
    city: string;
    country: string;
  }
}


const userJSON: string = '{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "isActive": true
}';

const decoded = UserCodec.decode(JSON.parse(userJSON));

if (isRight(decoded)) {
  const user: User = decoded.right;
  console.log(user.name);
} else {
  console.error('Validation errors:', decoded.left);
}

            

              
                Copy
              
            
          

У цьому прикладі `UserCodec.decode(JSON.parse(userJSON))` намагається декодувати та перевірити рядок `userJSON`. `isRight()` з бібліотеки `fp-ts` перевіряє результат валідації, і надаються помилки валідації, якщо декодований JSON не відповідає `UserCodec`.

Такі бібліотеки, як `zod` і `io-ts`, пропонують переваги безпечної десеріалізації JSON, надаючи:

• Валідація під час виконання: Вони перевіряють дані на відповідність схемі під час виконання, виявляючи помилки до того, як вони спричинять проблеми.
• Чіткі повідомлення про помилки: Вони надають конкретні та корисні повідомлення про помилки, щоб точно визначити проблеми валідації даних.
• Виведення типів: Вони часто добре працюють із виведенням типів TypeScript, що полегшує підтримку визначень типів.

3.3 Користувацькі функції десеріалізації

Інший підхід полягає в написанні користувацьких функцій десеріалізації, які обробляють перетворення даних JSON у ваші інтерфейси TypeScript. Це дозволяє обробляти певні типи даних або перетворення, яких важко досягти за допомогою простіших бібліотек валідації. Цей підхід забезпечує більший контроль, але вимагає більше зусиль.

Приклад:

            interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  createdAt: Date;
}

function deserializeUser(json: string): User | null {
  try {
    const parsed = JSON.parse(json);

    if (
      typeof parsed.id !== 'number' ||
      typeof parsed.name !== 'string' ||
      typeof parsed.email !== 'string' ||
      typeof parsed.isActive !== 'boolean' ||
      typeof parsed.createdAt !== 'string'
    ) {
      return null; // Invalid data
    }

    // Assuming createdAt is a string in ISO format
    const createdAtDate = new Date(parsed.createdAt);
    if (isNaN(createdAtDate.getTime())) {
      return null; //Invalid date
    }

    return {
      id: parsed.id,
      name: parsed.name,
      email: parsed.email,
      isActive: parsed.isActive,
      createdAt: createdAtDate,
    };
  } catch (error) {
    console.error('Deserialization error:', error);
    return null;
  }
}

const userJSON: string = '{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "isActive": true,
  "createdAt": "2024-01-26T10:00:00.000Z"
}';

const user: User | null = deserializeUser(userJSON);

if (user) {
  console.log(user.name);
  console.log(user.createdAt);
} else {
  console.log('Invalid user data');
}

            

              
                Copy
              
            
          

У цьому прикладі функція `deserializeUser` аналізує рядок JSON і перевіряє типи даних властивостей. Вона також обробляє перетворення властивості `createdAt` з рядка в об’єкт `Date`. Якщо дані недійсні, функція повертає `null`. Ця власна функція забезпечує повний контроль над процесом десеріалізації, дозволяючи обробляти складні перетворення даних.

4. Обробка необов’язкових властивостей і нульових значень

Дані JSON часто містять необов’язкові властивості та нульові значення. Система типів TypeScript надає механізми для обробки цих випадків ввічливо. Необов’язкові властивості позначаються суфіксом `?` у визначенні інтерфейсу. Нульові значення вимагають ретельного розгляду під час десеріалізації. Під час використання бібліотек валідації, таких як Zod, ви можете визначати необов’язкові поля за допомогою `z.optional()` або `z.nullable()`, щоб дозволити як `null`, так і undefined, залежно від структури JSON, яку повертає API.

Приклад:

            import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  isActive: z.boolean(),
  address: z.optional(z.object({
    street: z.string(),
    city: z.string(),
    country: z.string()
  })),
  profilePicture: z.nullable(z.string()) // Allows null values
});

interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: {
    street: string;
    city: string;
    country: string;
  };
  profilePicture: string | null; // Typescript interface reflects the nullable
}

const userJSONWithAddress: string = '{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "isActive": true,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "country": "USA"
  },
  "profilePicture": "/path/to/image.jpg"
}';

const userJSONWithoutAddress: string = '{
  "id": 456,
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "isActive": false,
  "profilePicture": null
}';

try {
    const userWithAddress: User = UserSchema.parse(JSON.parse(userJSONWithAddress));
    console.log(userWithAddress);

    const userWithoutAddress: User = UserSchema.parse(JSON.parse(userJSONWithoutAddress));
    console.log(userWithoutAddress);
} catch (error) {
    console.error("Validation error", error);
}

            

              
                Copy
              
            
          

У цьому прикладі властивість `address` є необов’язковою. `profilePicture` може мати строкові дані або `null`. Zod або подібні інструменти валідації обробляють валідацію даних.

5. Дженерики для повторного використання серіалізації та десеріалізації

Дженерики можна використовувати для створення функцій серіалізації та десеріалізації для повторного використання, які працюють з різними типами. Це зменшує дублювання коду та сприяє повторному використанню коду. Використання дженериків дозволяє писати функції, які можуть працювати з різними типами, не потребуючи написання окремих функцій для кожного типу.

Приклад:

            import { z, ZodSchema } from 'zod';

function safeParse(schema: ZodSchema, json: string): T | null {
  try {
    const parsed = JSON.parse(json);
    return schema.parse(parsed);
  } catch (error) {
    console.error('Parse error:', error);
    return null;
  }
}

interface Product {
  id: number;
  name: string;
  price: number;
}

const ProductSchema: ZodSchema = z.object({
  id: z.number(),
  name: z.string(),
  price: z.number()
});

const productJSON: string = '{
  "id": 1,
  "name": "Example Product",
  "price": 99.99
}';

const product: Product | null = safeParse(ProductSchema, productJSON);

if (product) {
  console.log(product.name);
} else {
  console.log('Invalid product data');
}

            

              
                Copy
              
            
          

Функція `safeParse` — це дженерик-функція, яка приймає схему Zod і рядок JSON. Вона аналізує рядок JSON і перевіряє його на відповідність наданій схемі. Якщо аналіз або валідація не вдаються, вона повертає `null`. Цю дженерик-функцію можна повторно використовувати для різних типів, просто передавши відповідну схему Zod.

Найкращі практики та розширені міркування

1. Найкращі практики валідації даних

• Централізовані визначення схеми: Визначте свої схеми в центральному місці, щоб забезпечити узгодженість і зручність обслуговування.
• Комплексна валідація: Перевірте всі властивості та типи даних.
• Обробка помилок: Реалізуйте надійну обробку помилок, щоб перехоплювати та повідомляти про помилки валідації.
• Версіонування схеми: Подумайте про версіонування схеми, коли ваш API або структура даних розвивається. Це дозволяє підтримувати кілька версій вашого формату даних, мінімізуючи критичні зміни.
• Тестування: Напишіть юніт-тести для своєї логіки серіалізації та десеріалізації, щоб переконатися в її правильності та надійності. Включіть тести для дійсних і недійсних сценаріїв даних.

2. Обробка складних структур даних

Для складних структур даних може знадобитися вкласти схеми або використовувати рекурсивні схеми у своїй бібліотеці валідації. Складні структури можна представити за допомогою вкладених інтерфейсів або шляхом компонування існуючих схем за допомогою бібліотек, таких як Zod або io-ts.

Приклад рекурсивної схеми з Zod:

            import { z } from 'zod';

interface TreeNode {
  value: string;
  children: TreeNode[];
}

const TreeNodeSchema: z.ZodSchema = z.object({
  value: z.string(),
  children: z.lazy(() => z.array(TreeNodeSchema)), // Recursive definition
});

const treeJSON: string = '{
  "value": "Root",
  "children": [
    {
      "value": "Child 1",
      "children": []
    },
    {
      "value": "Child 2",
      "children": [
        {
          "value": "Grandchild 1",
          "children": []
        }
      ]
    }
  ]
}';

try {
  const parsedTree: TreeNode = TreeNodeSchema.parse(JSON.parse(treeJSON));
  console.log(parsedTree);
} catch (error) {
  console.error("Validation error", error);
}

            

              
                Copy
              
            
          

Цей приклад демонструє, як визначити рекурсивну схему для деревоподібної структури даних за допомогою Zod.

3. Міркування щодо продуктивності

• Виберіть правильну бібліотеку: Виберіть бібліотеку валідації, яка відповідає вашим вимогам до продуктивності. Такі бібліотеки, як `zod` і `io-ts`, зазвичай є продуктивними, але продуктивність окремих бібліотек може відрізнятися.
• Оптимізуйте схеми: Ефективно розробляйте схеми. Уникайте непотрібних етапів валідації.
• Кешування: Кешуйте серіалізовані дані, коли це можливо, щоб уникнути повторних витрат на серіалізацію. Однак завжди надавайте пріоритет правильності даних над продуктивністю для критично важливих додатків.

4. Міркування щодо безпеки

• Очищення вхідних даних: Очистіть будь-які дані, надані користувачем, перед серіалізацією, щоб запобігти вразливостям до ін’єкцій. Це важливий аспект безпечного кодування, який гарантує, що зловмисний код не серіалізується та не десеріалізується.
• Валідація даних: Ретельно перевіряйте дані, щоб запобігти вразливостям. Надійна валідація допомагає захиститися від атак, коли зловмисники намагаються надати недійсні дані для запуску помилок або порушень безпеки.
• Уникайте `eval()` і `new Function()`: Ніколи не використовуйте `eval()` або `new Function()` з ненадійними даними JSON. Ці методи можуть створити серйозні ризики безпеці, дозволяючи довільне виконання коду.

5. Інтернаціоналізація та локалізація

Під час розробки глобальних додатків враховуйте вплив серіалізації та десеріалізації на інтернаціоналізацію (i18n) і локалізацію (l10n). У різних регіонах використовуються різні формати дати/часу, символи валют і правила форматування чисел. Ваша логіка серіалізації та десеріалізації повинна вміти обробляти ці варіації. Такі бібліотеки, як Moment.js або date-fns, часто використовуються для обробки форматування дати й часу. Розгляньте можливість використання об’єкта `Intl` у JavaScript для форматування чисел і валют для підтримки різних локалей.

Висновок: Створення надійних додатків у всьому світі

Система типів TypeScript у поєднанні з надійними бібліотеками валідації дає розробникам змогу створювати більш надійні та зручні в обслуговуванні додатки, забезпечуючи комплексну безпечну обробку JSON. Завдяки впровадженню шаблонів і методів, описаних у цьому посібнику, ви можете зменшити кількість помилок під час виконання, покращити цілісність даних і забезпечити стабільність своїх веб-додатків для користувачів у всьому світі. Безпека типів приносить користь не лише вашій команді розробників, покращуючи якість коду, але й покращує взаємодію з користувачем, запобігаючи несподіваним помилкам і забезпечуючи узгоджене представлення даних, що сприяє створенню більш надійного та надійного додатку в усьому світі.

Реалізація цих шаблонів, від визначення інтерфейсів і використання бібліотек валідації, таких як Zod і io-ts, до обробки необов’язкових властивостей і нульових значень, призведе до створення більш надійного та зручного в обслуговуванні коду. Не забувайте надавати пріоритет комплексній валідації, обробці помилок і найкращим практикам безпеки. Застосовуючи ці практики, розробники можуть створювати додатки, які є більш стійкими до помилок, легше підтримуються та забезпечують кращу взаємодію з користувачем у всіх регіонах і культурах.